Happy Git and Github for the useR
Session 06 - Daily Workflows, Part 2

Boook club R-Ladies Bergen, R-Ladies Den Bosch, R-Ladies Amsterdam

Josefina Bernardo

What we will cover today:

  • Time travel: See the past
  • Fork and clone
  • Get upstream changes for a fork
  • Explore and extend a pull request
  • Make a Github repo browsable

Chapter 30 - Time Travel: See the past

Looking at the history of a repository

Looking at specific commits

  • You can look at the commit, copy the SHA or browse the repository at that point in time

Looking at contributors for a specific file

  • By clicking on a specific file we can look at the Code, Preview (rendered code) and Blame

  • Blame is analogous to git blame

Chapter 31 - Fork and clone

When to fork and clone

  • If you want to propose a change to someone else’s repo

  • When in doubt, use ‘fork and clone’ over ‘just clone’

How to fork and clone

  • Method A: Browser, command line and RStudio

  • Method B: Using usethis::create_from_github()

  • Method C: Github Desktop

Method A: Browser, command line and RStudio

  • Click fork on the Github page of the original repo (OWNER/REPO) - creates a copy in your account (YOU/REPO)

  • Clone the newly create YOU/REPO onto your machine

  • Highly recommended: Configure the upstream remote in one of these ways

    • git remote add upstream https://github.com/OWNER/REPO.git

    • usethis::use_git_remote(name = "upstream", url = "https://github.com/OWNER/REPO.git")

    • Clicking on new branch and pasting the link of the original rep

Method A: Browser, command line and RStudio

  • Use git fetch upstream to pull changes from the upstream

  • Use git branch -u upstream/main to set the original repo as the tracking branch for your local branch

  • Pushes to and pulls from the original repo automatically

Method B: create_from_github()

  • This is much quicker and easier
usethis::create_from_github("https://github.com/OWNER/REPO")
  • Automatically stets the upstream as the tracking branch

Method C: Github Desktop

  • Download Github Desktop and connect your Github account

  • Fork the repository in Github, then clone

  • Same advantages as create_from_github()

Method C: Github Desktop

  • Might be a good option if you want to avoid using the command line altogether and prefer GUI

Some useful commands

  • git remote -v

  • git remote show origin

Don’t mess with main

  • Do not make commits to the main of a repo you have forked - this will create discrepancies

  • Instead: Create a new branch and use a pull request

What if you have messed with the main?

  • It’s recommended to always work in a new branch and not in the main of your forked repo

  • In this case no problem, we can sync the fork

  • However, we may run into issues if the original main is updated

Chapter 32 - Get upstream changes for a fork

When do we need to get upstream changes?

  • This is meant for when we fork & clone and there is an update to the OWNER/REPO (source repo)

Preparing for getting upstream changes

  • List your remotes:

    • git remote -v in the command line

    • usethis::git_remotes() in the console

  • Use git branch -vv to view the upstream tracking branch

Get changes from upstream

  • Create a new branch (and treat main as read-only)

Sync by pulling changes from upstream, then push to origin

  • git pull upstream main --ff-only and then git push origin main

Sync by pulling changes from the origin repo

  • Sync fork on Github and pull changes from origin repo

What if you touched the main?

  • Let’s say you have two mains:

    • The OWNER/REPO: A - B - C - D - E - F

    • YOUR/REPO: A - B - C - X - Y - Z

  • Create a new branch and switch to it, e.g., git checkout -b session-06

  • Then switch back to your main and do a hard reset, e.g., git checkout main and then reset the main to the previous compatible commit (git reset --hard C)

Chapter 33 - Explore and extend a pull request

Create a pull request

Pull requests with the usethis package

https://usethis.r-lib.org/articles/pr-functions.html

General steps

  • Fork and clone the original repository

  • Branch and make your change

  • Submit a pull request

  • Review pull request, merge and finish

Chapter 34 - Make a Github repo browsable

Browsability

  • One of Github’s advantages is that you can browse repositories in the browser

  • Derived products may be useful to your audience - so you may want to consider keeping file formats such as .md which can be viewed on Github

R Markdown

  • You can tweak a few options in the R Markdown settings to make it more Github-friendly

  • Keep the .md file

---
output:
  html_document:
    keep_md: TRUE
---
  • Render directly to a Github document
---
output: github_document
---

Other options

  • README.md files as a sort of landing page

  • Use t as a file finder

Other options

  • Github automatically renders .tsv and .csv files

  • Github pages, e.g., to host a website for an R package (you can do this via pkgdown)